QuickTime 3 Reference
The Sprite Toolbox is a set of data types and functions you can use to add sprite-based animation to an application. The Sprite Toolbox handles invalidating appropriate areas as sprite properties change, the composition of sprites and their background on an offscreen buffer, and the transfer of the result to the screen or an alternate destination.
To create a sprite track in a QuickTime movie, you use the sprite media handler, which, in turn, makes use of the Sprite Toolbox. For information on how to use the sprite media handler, see "Media Handlers: Sprites."
The next section describes the characteristics that govern creating sprite animation in an application.
Sprite animation differs substantially from traditional video animation. With traditional video animation, you describe a frame by specifying the color of each pixel. By contrast, with sprite animation , you describe a frame by specifying which sprites , or images, taken from a finite set of images, appear at various locations.
You can think of a sprite animation as a play. In a QuickTime movie, the sprite track bounds are the stage; in an application, a sprite world is the stage. The background is the play's set; the background may be a single solid color, an image, or a combination of images. The sprites are the actors in the play.
A sprite has properties that describe its location and appearance at a given point in time. During the course of an animation, you modify a sprite's properties to cause it to change its appearance and move around the set. For sprites in a sprite world, you modify a sprite's properties by calling the SetSpriteProperty function, passing a constant to indicate which property you want to modify. SetSpriteProperty invalidates the appropriate portions of the sprite world, which are redrawn when SpriteWorldIdle is called. For sprites in a sprite track, you modify a sprite property by creating an override sample of the appropriate type.
Each sprite has a corresponding image. During the animation, you can change a sprite's image. For example, you can assign a series of images to a sprite in succession to perform cell-based animation. For sprites in a sprite world, you control a sprite's image by setting the sprite's kSpritePropertyImageDescription and kSpritePropertyImageDataPtr properties.
For sprites in a sprite track, all sprite images are stored in the sprite track's key frame sample. This allows the sprites in the sprite track to share images. A sprite's image index ( kSpritePropertyImageIndex ) specifies the sprite's current image in the pool of available images. All images assigned to a sprite must share the same image description.
A sprite's matrix property ( kSpritePropertyMatrix ) describes the sprite's location and scaling within its sprite world or sprite track. A sprite's local coordinate system is defined by its natural bounding box, as shown in Figure 1 .
Figure 1 Local coordinate system of a sprite
A sprite's display coordinate system--where a sprite is displayed within a sprite world or a sprite track--is defined by the sprite's matrix, as shown in Figure 2 .
Figure 2 Display coordinate system of a sprite
By modifying a sprite's matrix, you can modify the sprite's location so that it appears to move in a smooth path on the screen or so that it jumps from one place to another. You can modify a sprite's size so that it shrinks, grows, or stretches. Depending on which image compressor is used to create the sprite images, other transformations, such as rotation, may be supported as well. Translation-only matrices provide the best performance.
A sprite's layer property ( kSpritePropertyLayer ) is a numeric value that specifies a sprite's layer in the animation. Sprites with lower layer numbers appear in front of sprites with higher layer numbers. To designate a sprite as a background sprite, you should assign it the special layer number kBackgroundSpriteLayerNum .
A sprite's visible property ( kSpritePropertyVisible ) specifies whether or not the sprite is visible. To make a sprite visible, you set the sprite's visible property to TRUE .
A sprite's graphics mode property ( kSpritePropertyGraphicsMode ) specifies a graphics mode and blend color that indicates how to blend a sprite with any sprites behind it and with the background. To set a sprite's graphics mode, you call SetSpriteProperty , passing a pointer to a ModifierTrackGraphicsModeRecord structure.
Three other properties, kSpriteTrackPropertyBackgroundColor , kSpriteTrackPropertyOffscreenBitDepth , and kSpriteTrackPropertySampleFormat , describe properties of a sprite track in a QuickTime movie. These properties are discussed in more detail in "Media Handlers: Sprites."
A sprite world is a graphics world for a sprite animation. To create a sprite animation in an application, you must first create a sprite world. You do not need to create a sprite world to create a sprite track in a QuickTime movie.
Once you have created a sprite world, you create sprites associated with that sprite world. You can think of a sprite world as a stage on which your sprites perform. When you dispose of a sprite world, its associated sprites are disposed of as well.
When you call SetSpriteProperty to modify a property of a sprite, SetSpriteProperty invalidates the appropriate regions of the sprite world. When your application calls SpriteWorldIdle , the sprite world redraws its invalid regions. A sprite's sprite world coordinate system is defined by translating the sprite's display coordinate system by the sprite world's matrix, as shown in Figure 3 .
Figure 3 Sprite world coordinate system
To achieve the best performance for your sprite animation, you should observe the following guidelines when creating a sprite world.